home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Meeting Pearls 1
/
Meeting Pearls Vol 1 (1994).iso
/
amok98-106
/
amok104
/
english
/
poster
next >
Wrap
Text File
|
1994-05-10
|
9KB
|
198 lines
===========================================================================
AMOK - Amiga Modula & Oberon Klub
"Poster": Norm bzw. Standardform für AMOK-Beiträge
Tips und Anhaltspunkte für Veröffentlichungen
===========================================================================
Introduction
AMOK welcomes also Modula-2 or Oberon programs, written by people other than
the club members, on the AMOK disks. The aim of the PD series is to spread
Modula & Oberon as far as possible. Since both languages support easy
exchange of the program modules, every programmer can contribute something.
The bigger the module library is, the easier it is to save time and work,
since you don't have to 'invent the wheel a second time'. If you have
written modules which you think that other might have use for them, then
send them to AMOK. If it is possible, we will publish it in our AMOK
series. We don't expect programs by genius', but if you want your program
published, you should obey the rules below. Like this it is guaranteed that
your program is really usefull.
1) Criteria
As mentioned above we don't expect anything revolutionary, but the program
should do what it is expected to do in a senseful and correct way. A simple
but useful module has got more chances, than a great project, which does
often crash!
2) AMOK demands
The following are obligatory for all AMOK submissions:
* Each module must be supported by documentation. Without documentation the
modules are useless for others. There are the following possibilities for
documentation on AMOK disks:
- documentation in an extra file with the suffix ".dok" (the German
documentation) or ".doc" (the English one)
- short description of the procedures in the definition modul. This is
all explained in 'HeaderInfo'.
The documentation should at least contain the following information:
- meaning and function of the parameter of the procedures
- function and usage of the procedures
- meaning and returning values of the procedures
- important notes on exporting variables, constants and types
- notes on bugs (if known)
- information on limits or warnings
If possible then write the documentation in pure ASCII code (so it can
be used with MuchMore and 'copy <file> to PRT:').
* Very important are also the files with the product information
(".product-info") which are specificated after the FishROM Database Draft
#5 (or higher, changes see below!). Without this the chance to get onto
an AMOK disk is very low.
A description of the file format is on disk (file 'Product-Info.Spec').
You should use English for description, but any other language is better
than nothing.
We have decided to use the .product-info format by Fred Fish. This has
many advantages:
- just ONE description for AMOK and Fish
- KingFisher is able to administer AMOK disks
- we can create the contents files automatically
The format must be used as it is, but there are some changes from Draft #6
by Fred Fish:
--> .reference is not optional for AMOK files. It must be supplied if
there exists an earlier version in order to create a link to that
version.
Ex.:
--------schnipp--------
.reference
AMOK#99:DrawA5000/
1.0
--------schnapp--------
Creates e.g. "Update to version 1.0 on AMOK #99"
--> Source is not optional. This string is searched for the following
keywords: Oberon, Modula, M2, Arexx. The keywords then appear directly
after the name (in brackets). Ex.:
DrawA5000 1.1 (Oberon/Modula/Arexx)
--> We introduced a new field: .beschreibung
This schould contain the description in german language. This field
is used to generate the file 'Inhalt'.
You can find examples on each AMOK disk (upto 103 only as 'mini-info',
which was created by ourselves).
* The modules should always have their source code with them. Like this
other programmers are able to learn something from your program and it is
then possible to remove some bugs or one is able to configure the program
for one's needs. But there are some exceptions:
- the program is really exceptional and should be patented (it must be
totally bugfree)
- the modules are part of a commercially distributed program and you
don't want others to steal parts of it
- your programming is so bad and your methods so abstruse, that you
don't want to take the risk others seeing your source code (in this
case you should think about changing to C or Assembler!)
* Definition and implementation modules should contain our module header
(see 'HeaderInfo'). This is necessary, since the AMOK library contains
already some Megabyte. Please stick with the format in 'HeaderInfo'.
* All files and directories should have icons, so that they are easily
accessible from Workbench. The default tool for text files (source and
documentation) should be '
:c/MuchMore
'.
3) AMOK conventions
Please obey the following:
* If you use non standard modules for compiling then you should supply them.
Please take care that the sym-key is correct, i.e. everything is compiled
with the same definition module. If there are more than one version of an
imported module, then state the required one (:Imports.).
* Please use only 70 to 75 characters in the source code and the
documentation. MuchMore and M2Emacs accept up to 80 characters, but if
you print the text, it is quite useful to have a little space on one
margin.
* Procedure, variables, constants and type names should be English. The
same applies for the short descriptions of the procedures (see AMOK#7,
ProgInfo/StandardIDs). You shouldn't mix English with other languages.
* If have small demos, you can use them to easily demonstrate the functions
of a module. In most cases are test modules or other examples already
there, because they are 'side effects' of your actual program.
* Please be fair about other programmers. PD does not mean that you can
steal whatever you like. If you take parts from others, then mention the
author in the module header or in remark lines. If you want to use them
commercially you need a written permission of the author. And please
don't forget the shareware fees.
4) Programming guidelines
The following is not only important for AMOK disks, but should be dealt with
by all programmers. If these information are not evident for you, then you
should change your programms IMMEDIATELY!
* All programs must be programmed according to the guidelines of the ROM
Kernal Reference Manuals.
- Amiga User Interface Style Guide ISBN 0-201-57757-7, Addison-Wesley
- Amiga ROM Kernel Manual: Libraries ISBN 0-201-56774-1, Addison-Wesley
- Amiga ROM Kernel Manual: Includes & Autodocs ISBN 0-201-56773-3, A.-W.
- Amiga ROM Kernel Manual: Devices ISBN 0-201-56775-X, Addison-Wesley
- Amiga Hardware Manual ISBN 0-201-56776-8, Addison-Wesley
- The Amiga Guru Book, Ralph Babel, published by author
- Native Developer's Update 3.1 (Examples, Debugging-Tools, Includes,
Autodocs)
* All programs must have an exit, i.e. you don't have to reboot the
computer and everything should be in the same state as before starting the
program. All devices and resources must be released (deallocation of
memory, closure of windows, screens and files).
* Programs
shouldn't
behave as if they were the only program in the system.
They should take care of the multitasking and its restrictions (e.g.
usage of devices and resources).
* All programs should work logically and shouldn't fail with false entries.
* Never expect to get all resources you need. Programs should always have a
defined way of exit, if e.g. a file couldn't be opened or if there isn't
enough memory left.
* The user interface should be standard AMIGA one (see Amiga User Interface
Style Guide).
* The programs shouldn't rely on a certain device configuration (e.g. A500+
with 2 MB and 3 disk drives).
* It is important for future library modules to make the procedures
reentrant. Just in case it makes sense to use them from different tasks
at the same time (in Modula it is not possible to import the same module
twice).
--- Have fun